Taeluf.com

Extensions

Code Scrawl Extensions allow library developers to create their own documentation generators, shareable templates and MDVerbs, and hook into various Code Scrawl events.

If you're not a library developer, it's easier to use a @\system() call to a bin script, add template directories in your config, or add markdown verbs in your configured bootstrap.

Also see: Templates, Markdown Verbs, Configuration

Docs

  • Enabling & Configuring Extensions
  • Built-In Extensions
  • Create an Extension
  • Useful Scrawl Methods

Enabling & Configuring Extensions

Option 1:

  1. Configure scrawl.extensions with an array of Fully Qualified Class Names. Example: "scrawl.extensions": ["Tlf\\Scrawl\\Extension\\Notes"] (Each class must implement Tlf\Scrawl\Extension)
  2. See the Extension's documentation to learn how to configure it.

Option 2:
Instantiate in your configured bootstrap.php file. (Option 1 is preferred, unless the Extension's documentation suggests otherwise.)

scrawl-bootstrap.php:

<?php  
$ext = new \Some\ScrawlExtension($this);  
$ext->some_option = true;  
$ext->some_path = __DIR__;  
  
// $this is the `Tlf\Scrawl` instance  
$this->ScrawlExtensions[] = $ext;

Built-In Extensions

Optional Extensions: (Must be enabled via scrawl.extensions)

  • Tlf\Scrawl\Extension\Notes - Creates Notes.md documentation file listing all @\NOTE lines in scanned directories.

Other Extensions:

  • Tlf\Scrawl\DoNothingExtension - base class for other Extensions to extend from
  • Tlf\Scrawl\Ext\MdVerb\MainVerbs - enables all the built-in Markdown Verbs. It is loaded automatically and cannot be configured.

Note: There are other classes providing features that do not use the Extension interface. This may be changed in the future.

Create an Extension

  1. Create a class that implements \Tlf\Scrawl\Extension OR extends \Tlf\Scrawl\DoNothingExtension for easier setup, and implement any methods you need.
  2. Add features: (Reference $this->scrawl as needed, and use the 'Useful Scrawl Methods' below when working with files.)
    • Implement/Override any methods you need (and code whatever you want)
    • Add template directories (during bootstrap) ($scrawl->add_template_dir($absolute_path))
    • Create Markdown Verbs (during bootstrap) ($scrawl->add_md_verb('verb_name', $callable)

See Extension Interface and DoNothingExtension.

Useful Scrawl Methods

  • public function add_md_verb(string $verb_name, $callable) - Add a Markdown Verb. The callable accepts the arguments as they are passed to the @\verb(arg1,arg2) call.
  • public function add_template_dir(string $dir) - Add a template directory containing .md.php files.
  • public function parse_rel_path(string $base_path, string $target_path, bool $use_realpath = true): string - Get the relative path within target_path, if it starts with root_path
  • public function write_doc(string $rel_path, string $content) - save a file to disk in the documents directory
  • public function write_file(string $rel_path, string $content) - save a file to disk in the root directory
  • public function read_file(string $rel_path) - Read a file from disk, from the project root
  • public function read_doc(string $rel_path) - Read a file from disk, from the project docs dir
  • public function doc_path(string $rel_path) - get a path to a docs file
  • public function warn($header, $message) - Output a message to cli, header highlighted in red
  • public function good($header, $message) - Output a message to cli, header highlighted in green
  • public function prepare_md_content(string $markdown) - apply small fixes to markdown
  • public function get_ast(string $file): array - Get an array AST from a PHP file